feat(fx): add resilient provider caching and stale-data semantics - #141

Reclassify the quoted FX snapshot at use time while preserving its price and identity. Enforce quote and FX grace expiry boundaries, and return current stale metadata for the explicit opt-in policy.

Validation: 20 focused FX tests and 278 repository tests pass. A real local HTTP quote-to-transfer flow previously accepted an expired FX snapshot with 201 and rateStale=false; it now returns 409 QUOTE_STALE before creating a transfer. Explicit within-grace stale policy returns 201 with rateStale=true and unchanged quote terms; a fresh quote returns 201 with rateStale=false. The application uses its documented in-memory store and mock Stellar adapter.

A successful fetch could return an old snapshot, bypass reject_stale during cache refresh, and mint a transfer without a supplied quoteId. Even an expired primary snapshot hid a usable fallback.

Apply the caller's freshness policy before a provider wins or replaces the cache. Fresh snapshots remain eligible; allow_stale also permits visibly stale snapshots strictly within grace. Reject non-finite or non-numeric timestamps. An unusable response advances the ordered fallback registry, and a failed refresh preserves an existing within-grace display snapshot. Keep original provider timestamps and the prior bound-quote freshness repair.

Validation: npm test passed 283/283, zero skipped or failed. The existing FX file now has 25 checks; all five new regressions fail on sole parent 321b1da and its 20 previous checks pass. Node 24.19.0 reused retained packages matching all 76 lockfile package versions, without an install. Changed JavaScript syntax and git diff checks pass.

Actual local Express HTTP replay with the documented in-memory store and mock Stellar adapter: snapshots at TTL and grace expiry previously produced 201/rateStale:true; both now return 503 FX_PROVIDERS_DOWN with zero transfers, quotes, or idempotency records. A fresh fallback now produces 201/rateStale:false after the stale primary, and a recovered provider can reuse the rejected request's idempotency key. No live FX, Stellar settlement, or hosted Node 22 CI result is claimed.

The existing FX implementation exposes four environment settings and
versioned quote binding, but the README and example environment omit that
operating contract. A caller following only the documented transfer body
intentionally receives a new quote rather than binding displayed terms.

Document the implemented defaults, FX-versus-HTTP cache lifetimes, optional
quoteId flow, current expiry/error policies, idempotent retry identity,
static default providers and process-local retention. Add the already
required Idempotency-Key to the existing fresh-pricing request example.

README.md and .env.example only; all 174 other file blobs and modes,
including the existing quote/freshness/provider repairs and tests, remain
unchanged. The environment example uses the current defaults.

Validation: API source/document comparison and exact prepared tree readback.
Current npm test on Node 22, request examples and Markdown preview are unrun
because native execution is offline. No runtime or suite replay; the prior
286 full / 28 focused test results remain historical at cdbdb17.

Refs RemitFlow#129 and existing PR RemitFlow#141.

A finite provider fetchedAt ahead of the request time previously extended
freshness beyond the configured TTL and prevented a usable fallback from
being considered. Reject these candidates instead of clamping their source
timestamps. Exact-now snapshots remain valid, and existing stale-cache
outage/grace behavior is preserved.

Add four node:test regressions covering ordered fallback under both
policies (1 ms, TTL and one-day offsets), no-cache rejection and recovery,
stale-cache preservation/grace expiry, and the exact-now/TTL boundary.
The existing npm test glob includes the new file; no existing tests change.

Validation: node --test test/fxFutureTimestamp.test.js on Node 22.16.0.
Original fxCacheService blob df824e5:
1 pass / 3 fail (exit 1). Repaired source: 4 pass / 0 fail (exit 0).
Native syntax checks pass. Execution used the exact cache/provider/error/
rate modules with a local ordinary-values config fixture because dotenv
is unavailable in the offline runtime. That fixture is NOT committed.
This is focused module execution, not full application, HTTP or CI proof.

Refs RemitFlow#129 and existing PR RemitFlow#141.

Memoize a quote's parsed expiry string in a WeakMap rather than reparsing
it on every live-quote scan. Changed strings are reparsed, non-string
values remain uncached, and grace is still applied at collection time.
No quote DTO fields, expiry boundaries, capacity or eviction order change.
Weak keys do not themselves retain evicted quote objects.

Retain a dependency-free GC-kernel benchmark and three focused node:test
regressions. The new tests report 2 pass/1 fail on baseline and 3 pass/0 fail
on the patch. Existing tests and application exports remain unchanged.

Measured Node 22.16.0, 20,000 live inserts, five warm timed samples:
median collector time 2733.05 -> 1730.78 ms (36.67% lower, 1.58x).
Separate parse count 7,587,952 -> 19,999 (99.74% lower).
Both versions retain the same 288 quote IDs and matching survivor digest.

These are isolated actual-GC-code results with store/config fixtures,
not HTTP, application, FX-provider or fleet throughput. Heap usage and
full application/CI were not measured. The report records complete source
blob IDs, all timings, commands and the memory/correctness tradeoffs.

Refs RemitFlow#129 and existing PR RemitFlow#141.

Require every configured supported currency in the provider's copied USD
snapshot before freshness admission or cache replacement. Missing or
inherited-only rates now fall through to the next provider rather than
hiding a healthy fallback and failing supported pairs downstream.

Preserve deterministic provider order, complete default rates, freshness
admission and the existing structured FX_PROVIDERS_DOWN error.

Reproduced on parent 6c013e9: a USD-only primary was accepted, EUR was
missing, and the healthy fallback was never called. Focused validation:
node --test test/fxProviderCompleteness.test.js — 3 passed, 0 failed;
includes omission of each of the nine supported currencies, inherited-only
rates, all-provider failure, complete defaults and freshness admission.
Executed with Node 22.16.0 against the actual provider/config/error modules;
no live oracle, HTTP deployment or full-suite result is claimed.

Refs RemitFlow#129; retains existing PR RemitFlow#141.

Align existing provider fixtures with the all-supported-currencies snapshot
contract. Preserve every assertion and the intentionally invalid EUR/GBP
values, array responses, expiry boundaries and retry behavior. The new
focused completeness tests retain explicit missing-currency cases.

Fixture-only follow-through for a4e32b3; no additional test run claimed.

A synchronous provider can consume the remaining FX or quote TTL after
resolveForTransfer captures its initial timestamp. Recheck the minted
quote at completion before returning it to settlement; retain explicit
caller clocks, immutable quote terms and bounded stale-transfer opt-in.

Add four focused regressions to the existing FX test file. Against parent
52b48ff all four fail: expired FX and
expired quote terms reach mock settlement, age remains zero, and opted-in
stale terms are mislabeled. The repaired source passes all four plus six
existing fallback, singleflight and quote-binding controls (10/10).

Executed with Node 24.19.0 on the complete production modules and the
repository's simulated Stellar adapter, using controlled provider/Date
advancement, no sleeps. The local environment has uuid but no dotenv;
only dotenv.config initialization was externally shimmed inert, leaving
actual config/source unchanged. No HTTP, live-provider, full-suite or CI
result is asserted. No dependency or existing assertion changed.

Reproduce with installed project dependencies:
node --test --test-name-pattern='^(transfer mint completion|primary failure falls back|stampede: re-entrant|transfer creation binds|transfer rejects a quoteId|transfer without quoteId|stale transfer opt-in)' test/fxCache.test.js

Recheck provider admission and outage grace at completion. Each fallback sees the current clock; explicitly supplied times remain deterministic. A real 41 ms fetch under a 20 ms TTL previously returned stale data as fresh, age zero; it now selects the healthy fallback with accurate freshness.

Reuse the existing rate-precision correction from b685aae: NGN/USD remains 0.00065 instead of zero in pair and quote responses. Preserve amount rounding, snapshot provenance, and the transfer-completion repair from 76c74a0.

Add four timing and two precision regressions; align complete-rate and exact-ratio fixtures without dropping assertions. Focused cache checks passed 8/8, precision 2/2, and the four new transfer-completion controls pass after the exact-ratio fixture correction. Actual production modules on Node 24.19.0 with retained dotenv 17.3.1 and uuid 3.4.0; dependency versions differ from the project lock. No full-suite, HTTP, live-provider or hosted CI result asserted.

Forward only explicit caller timestamps from quote and implicit-transfer paths. Normal requests now reach the provider-completion checks and healthy fallback instead of freezing admission time before provider work. Honor the existing bounded stale-transfer opt-in when minting; retain completion-time quote validation and all rate precision changes.

Two added regressions fail on e91ea67: a display quote accepts an expired primary and an unquoted transfer rejects before trying the healthy fallback. Both now succeed with the current fallback. The combined six timing/boundary cases pass with actual production modules and the existing simulated settlement adapter.

Expired provider responses now raise the existing FX_PROVIDERS_DOWN 503 before any quote or settlement; expired issued quote terms still raise QUOTE_EXPIRED. Within-grace opt-in, explicit clocks, zero settlement on refusal, quote identity and exact rates remain covered. Existing assertions now reflect current issuance age and the earlier provider rejection point. Node 24.19.0 with retained dotenv 17.3.1 and uuid 3.4.0; no HTTP, live-provider, full-suite or hosted CI claim.

Provider failures were copied verbatim into ApiError.details and serialized by the HTTP error handler. Adapter exceptions may contain credentials, URLs or upstream response bodies. Keep each configured provider ID and ordered attempt, but expose only the stable message "FX provider failed". Preserve FX_PROVIDERS_DOWN, HTTP 503, snapshot validation, freshness and fallback selection.

Add one maintained HTTP regression using synthetic Error and string failures. It verifies safe ordered attempts, no cached snapshot or persisted quote/transfer on failure, and successful fallback recovery while the primary still fails.

Executed node --test test/fxProviderErrors.test.js with locked npm ci dependencies on Ubuntu 24.04.5 / Node 22.23.3 / npm 10.9.9. Original provider blob e40187c: 0 pass, 1 expected assertion failure exposing the synthetic message. Repaired provider blob eea2bb6: 1 pass, 0 fail, 0 skipped. Test blob acc6b99. No full-suite or live-provider claim.

Execution: https://github.com/woahwhattheheck/RemitFlow-Backend/actions/runs/37202463765
Artifact: fx-provider-error-before-after, ID 11303342530, SHA256 1744513a14263afe1bf70f717186a5ce03d2d0d7e59b76548b447b9b64a52c95. Validation workflow remains on its separate branch; original CI configuration is unchanged.

Positive finite table entries do not guarantee usable currency ratios. Reject a snapshot when its maximum/minimum configured rate overflows, before snapshot acceptance or cache replacement, so a usable later provider can win. This also excludes tables whose reverse ratio underflows to zero. Preserve provider order, cloned rate values, freshness admission and the existing redacted FX_PROVIDERS_DOWN error. Per-request converted-amount bounds remain separate.

Add three focused Node tests for malformed-table fallback, exhaustion with ordered diagnostics, and valid large common scales. Executed actual production fxProviders, rates and ApiError modules without substitutes or dependency installation on Node v22.16.0:
  node --test test/fxProviderRatios.test.js
Baseline provider eea2bb6: 1 pass, 2 fail.
Changed provider feaff60: 3 pass, 0 fail, 0 skipped.
Test blob d60d988; unchanged rates 52f235a and ApiError 6b586f6 were byte-verified before execution.

Only provider admission and its focused regression change. This is module-level local evidence, not a full-suite, HTTP, real-provider or settlement run. No CI/dependency or existing contributor-history changes.

Check configured currencies before materializing a cached rate snapshot. Preserve normalized input, provider-added currencies and all pricing/freshness paths.

One focused regression passes with the documented offline full-source component loader. Original lookup makes 18 unnecessary cache peeks; candidate makes zero for configured and invalid inputs. Seven alternating paired microbenchmark samples measured warm configured lookup medians of 95.431 to 26.843 ms per 500,000 calls, matching outputs. These are lookup-only component results, not full-app, hosted CI or provider measurements.

Preserve the concurrent provider-ratio repair f2c4741 in full. The report's parent 8f3bf8b identifies the benchmark baseline, not this integration parent; all four measured module preimages are unchanged by f2c4741. Exactly three leaf changes: rateService, one maintained regression and its source-pinned measurement/reproducer report. No dependency, workflow, provider or settlement changes.

Validate the unrounded FX-converted receive amount with the existing safe-money bound before rounding, issuing a quote identity or storing it. Preserve ordinary quote terms, binding, and stale/TTL policy.

Retain both concurrent provider-ratio and configured-currency lookup changes from parent 4efd7b7. Exactly three leaf changes: quoteService, three focused cases in the existing precision test, and a source-pinned execution note.

Actual Node 22.16 offline component run on current dependency blobs: original quote service 2 passed / 3 failed; candidate 5 passed / 0 failed / 0 skipped. Complete production quote/rate/cache/provider/money/config/store modules were loaded; only dotenv/UUID imports and unused audit/index initialization used the documented adapter. No HTTP transfer, live provider, dependency-complete suite or hosted CI claim. Source blob 4438da7; test blob cfe9565.

Cache failed refreshes for one second per freshness policy, preserving stale-display grace and strict transfer rejection. Start cooldown after provider failure, retry on the next request at its deadline, clear recovered state, and avoid extending holds on clock rollback.

Three focused node:test regressions fail on parent source and pass with this change. A deterministic 1,000-request/900ms adapter benchmark reduces both outage scenarios from 2,000 provider attempts to 2, with unchanged response outcomes; healthy caching remains one provider call. Adds the runnable benchmark script.

Validation used Node 22.16 and exact dependency source blobs with only dotenv initialization replaced by a local no-op because dependency download DNS was unavailable. No full-suite, hosted CI, live-provider or HTTP benchmark claim.